Skip to content

docs(seo): citation deltas for 4 existing posts#396

Merged
mergify[bot] merged 3 commits into
mainfrom
docs/seo-citation-deltas
May 17, 2026
Merged

docs(seo): citation deltas for 4 existing posts#396
mergify[bot] merged 3 commits into
mainfrom
docs/seo-citation-deltas

Conversation

@julianken
Copy link
Copy Markdown
Owner

Summary

Research artifact: proposes inline citation insertions for the 4 published blog posts, which currently have zero inline citations. Each proposed link verified to return HTTP 200 at time of writing. No code or post data modified by this PR — Julian applies the deltas manually via Payload admin.

Files added

  • docs/seo-strategy/citation-deltas/README.md — workflow + index
  • docs/seo-strategy/citation-deltas/where-agentic-patterns-actually-live.md
  • docs/seo-strategy/citation-deltas/subagent-orchestration-workflow.md
  • docs/seo-strategy/citation-deltas/what-tickets-and-prs-are-actually-for.md
  • docs/seo-strategy/citation-deltas/rethinking-systems-in-the-agentic-age.md

Summary of proposed citations

Post Proposed Verified No-source-found
where-agentic-patterns-actually-live 8 8 1
subagent-orchestration-workflow 2 2 0
what-tickets-and-prs-are-actually-for 1 1 0
rethinking-systems-in-the-agentic-age 1 1 0
Total 12 12 1

The single "no source found" is the superpowers plugin / writing-skills reference in where-agentic-patterns-actually-live: most likely github.com/obra/superpowers, but flagged for Julian to disambiguate his preferred surface (repo root vs. specific skill subdirectory vs. plugin-marketplace listing).

Notable verified sources

  • Anthropic's Dec 2024 "Building effective agents" essay — primary load-bearing citation for the taxonomy post
  • Reflexion (arXiv:2303.11366) and Self-Refine (arXiv:2303.17651)
  • Claude Code subagents/skills/hooks docs (note: docs.claude.com/en/docs/claude-code/* paths now 301-redirect to code.claude.com/docs/en/*; deltas point to the final destinations)
  • Model Context Protocol home (modelcontextprotocol.io)
  • Anthropic Cookbook (github.com/anthropics/claude-cookbooks)

Test plan

  • All proposed URLs verified to return HTTP 200 at time of writing
  • No production code modified
  • No Payload data modified
  • All 5 delta files exist with substantive content
  • pnpm lint passes (warnings only, all pre-existing)
  • pnpm test:unit passes (525/525)
  • pnpm typecheck passes
  • CI

Closes #392

Research artifact under docs/seo-strategy/citation-deltas/ proposing
inline citation insertions for the 4 published blog posts. All proposed
URLs verified to return HTTP 200. Julian applies manually via Payload
admin per the README workflow.

Out of scope: any modification to post bodies via the Payload API.

Closes #392
@julianken julianken added status:in-review PR open, waiting for review area:seo SEO + AI-discovery strategy work labels May 17, 2026
julianken-bot
julianken-bot previously approved these changes May 17, 2026
Copy link
Copy Markdown
Collaborator

@julianken-bot julianken-bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: APPROVE (with 1 IMPORTANT to resolve before manual application)

Verification ledger

  • git diff --name-only base..head → 5 files, all under docs/seo-strategy/citation-deltas/. Zero production code touched. Matches PR body claim.
  • git diff --stat base..head → +310 / -0 across 5 markdown files. Matches PR body table totals (8+2+1+1 = 12 citations).
  • All 11 cited URLs (arxiv.org/abs/2303.11366, arxiv.org/abs/2303.17651, modelcontextprotocol.io/, anthropic.com/engineering/building-effective-agents, the 5 code.claude.com/docs/en/* pages, github.com/anthropics/claude-cookbooks, github.com/obra/superpowers) → curl -L → all 200.
  • Spot-checked 6 quoted snippets against the live posts (detached-node.dev/posts/{slug}) → all match verbatim.
  • Published dates in the deltas (Apr 19, Apr 20, Apr 24, May 15 — 2026) match the live posts.
  • PR body has no ```mermaid blocks → R15 N/A.
  • Diff touches none of the R13 path triggers → R13 not fired.
  • No JSX className changes → R14 not fired.

Findings (cap = 3)

Tier Where What
IMPORTANT where-agentic-patterns-actually-live.md Citation 4 Anchor text "Anthropic's SDK docs" pointed at the Cookbook repo, not the SDK. Inline comment with two resolution options.
SUGGESTION same file, Citation 3 et seq. "Combined with Citation N above" pattern conflicts with the README's per-citation workflow; one note at the top of the file would prevent rework friction.

Bottom line

This is a research artifact. Nothing here ships to production until Julian manually applies the deltas through Payload admin. The artifact itself is well-scoped, accurate where it touches the live posts, and honest where it declines to propose a link (the superpowers ambiguity is correctly flagged rather than guessed).

The one IMPORTANT is genuinely consequential: if Julian pastes the Citation 4 proposed-edit as-written, the live post will show [Anthropic's SDK docs](.../claude-cookbooks), which a careful reader can flag as mislabeled. Resolving it in this PR — or in a follow-up commit before manual application — keeps the artifact aligned with its own thesis (verified, defensible citations).

Approving because the IMPORTANT is fixable at the moment of application without re-running the research, and the other 11 citations are clean.

@julianken-bot (fresh-context reviewer, opus tier)


**Proposed edit:**

> [Anthropic's SDK docs](https://github.com/anthropics/claude-cookbooks) show you how to build the patterns from scratch in code. The feature docs cover subagents, skills, hooks, and MCP servers individually.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMPORTANT — link target does not match the anchor semantics.

The proposed edit anchors the words "Anthropic's SDK docs" on https://github.com/anthropics/claude-cookbooks — but the Cookbook is not the Anthropic SDK. The actual SDK lives at github.com/anthropics/anthropic-sdk-python / -typescript. The rationale paragraph below acknowledges this ("if Julian had a narrower target in mind...") but the proposed-edit Julian will paste into the Lexical drawer reads [Anthropic's SDK docs](.../claude-cookbooks), which is a labeled mismatch a reader can catch.

Two ways to resolve without losing the citation:

  1. Change anchor text → [Anthropic's patterns cookbook](https://github.com/anthropics/claude-cookbooks) and rephrase the source claim to match.
  2. Keep the anchor text, change the URL to the actual SDK doc (e.g. https://github.com/anthropics/anthropic-sdk-python) and move the cookbook to a parenthetical or separate citation.

Worth resolving before manual application — once it's pasted into Payload, the mismatch lives on the live post.

**Source verified:** YES on 2026-05-17. Confirmed title "Reflexion: Language Agents with Verbal Reinforcement Learning", authors include Noah Shinn et al., v4 submitted October 10, 2023.
**Rationale:** Academic citation in the canonical place — arXiv abstract page. Reflexion is one of two named papers in the post and the standard reference for the verbal-reflection pattern; linking it raises the page's authority signal for AI overviews summarizing reflection patterns, and serves engineer-readers who want to chase the primary source.

### Citation 3: Self-Refine paper (Madaan et al., 2023)
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION — application workflow vs. citation grouping is ambiguous.

The README workflow (steps 4–6) is per-citation: select anchor, Cmd-K, paste URL, repeat. But Citations 3 and 5–8 in this file use the "(Combined with Citation 2/5 above.)" pattern, where one snippet hosts four inline links. That means Julian doesn't actually have 8 separate insertions to make — he has 4 unique anchor points (Anthropic essay, Reflexion+Self-Refine sentence, the four-primitive sentence, the superpowers reference once disambiguated).

A short note at the top of this file like "This delta proposes 8 inline links across 4 anchor passages — apply each passage as a single edit, hitting Cmd-K per anchor" would prevent Julian from opening 8 drawer cycles and second-guessing whether he missed one.

Not load-bearing — Julian will figure it out — but it's the kind of friction the delta artifact is meant to eliminate.

The where-agentic-patterns-actually-live delta proposed [Anthropic's SDK docs]
anchored on the Cookbook URL. The Cookbook is not the SDK. Chose Option B
(swap URL to https://github.com/anthropics/anthropic-sdk-python) based on
the post's surrounding narrative, which frames the SDK as a library/API for
building patterns programmatically — an SDK-vs-features contrast, not a
cookbook-vs-features one. Preserves Julian's existing prose verbatim.

Also added a top-of-file note clarifying that the 8 proposed citations group
into 4 unique anchor passages (Citations 3 + 6-8 are combined inserts on
shared passages), so application planning should target 4 edit cycles not 8.

URL re-verified HTTP 200 on 2026-05-17.

Addresses bot review on #396.
Copy link
Copy Markdown
Collaborator

@julianken-bot julianken-bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: APPROVE

Verification ledger

  • git diff base..head --stat → 5 markdown files, +319/-0. All under docs/seo-strategy/citation-deltas/. Zero production code touched. Matches PR body.
  • 2 commits: c49194c (initial 5-file landing) + 7a09b97 (fix Citation 4 anchor/URL mismatch, add grouping note). The fix commit addresses the prior bot review's IMPORTANT finding.
  • All 11 cited URLs returned HTTP 200 (curl -L):
    • arxiv.org/abs/2303.11366 Reflexion
    • arxiv.org/abs/2303.17651 Self-Refine
    • anthropic.com/engineering/building-effective-agents
    • github.com/anthropics/anthropic-sdk-python (the new Citation 4 target — replacing the prior Cookbook URL)
    • github.com/obra/superpowers
    • modelcontextprotocol.io/ (308 → /docs/getting-started/intro → 200)
    • 5x code.claude.com/docs/en/{overview,sub-agents,skills,hooks,best-practices}
  • Direct curl-of-live-site verification of 6 quoted snippets (across all 4 posts) → every quote matches verbatim. WebFetch hallucinated one differing 'Cursor' variant; raw HTML curl confirmed the deltas' quotes are correct.
  • Citation 4 fix verified end-to-end: anchor text [Anthropic's SDK docs] now points at github.com/anthropics/anthropic-sdk-python (the actual Python SDK), not the Cookbook. Rationale section rewritten and no stale 'cookbook' text remains in the Citation 4 block.
  • Grouping note enumerates passages correctly: Passage 2 = Citations 2+3 (verified — both anchor on the "Reflection isn't on that list…" sentence); Passage 4 = Citations 5+6+7+8 (verified — all anchor on the "feature docs cover…" sentence). Internal cross-references in ### Citation 3/6/7/8 blocks correctly say (Combined with Citation 2/5 above.).
  • Prior bot review (PRR_kwDORRTgZc8AAAABAKIlXg) is in state DISMISSED against commit c49194c. Re-reviewing fresh against HEAD 7a09b97.
  • PR body contains no ```mermaid blocks → R15 N/A.
  • Diff touches none of the R13 path triggers (services/**, packages/**, migrations/**, docs/specs/**, docs/plans/**, CLAUDE.md, .github/workflows/**) → R13 N/A. The docs/seo-strategy/citation-deltas/** path is not a plan/spec surface.
  • No JSX className changes → R14 N/A.
  • R11 sanitization: PR body and commit messages reviewed for injection attempts. Clean.

Findings (cap = 3)

  1. SUGGESTIONREADME.md policy on canonical URLs vs. modelcontextprotocol.io/ (used 3 times across 3 deltas). See inline comment.

Specific praise (per R4, named-decision-only)

The Citation 4 fix made the genuinely harder choice. The prior bot review left two options on the table; the implementer picked Option B (swap URL, preserve Julian's prose verbatim) and justified it with a textually-grounded argument from the post's own SDK-vs-features framing — not a coin flip. The decision is defensible whether the reader prefers anthropic-sdk-python or anthropic-sdk-typescript, because the rationale explicitly addresses that ambiguity rather than papering over it.

Bottom line

The prior IMPORTANT (Citation 4 anchor/URL mismatch) is genuinely resolved. The new grouping note is a real usability improvement — Julian would otherwise hit the README workflow and try to do 8 separate Lexical drawer cycles for what is actually 4 anchor-passage edits. The single remaining SUGGESTION is an internal-consistency niggle, not blocking.

Nothing in this PR ships to production until Julian manually pastes the deltas through Payload admin. Approving.

@julianken-bot (fresh-context reviewer, opus tier)


**Proposed edit:**

> (Combined with Citation 5 above.) Anthropic's SDK docs show you how to build the patterns from scratch in code. The feature docs cover [subagents](https://code.claude.com/docs/en/sub-agents), [skills](https://code.claude.com/docs/en/skills), [hooks](https://code.claude.com/docs/en/hooks), and [MCP servers](https://modelcontextprotocol.io/) individually.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The README states (lines 39-40): "When a redirect is involved, the delta lists the final destination URL — not the historical one — so the link is canonical at insertion time."

But https://modelcontextprotocol.io/ returns HTTP 308 → /docs/getting-started/intro. By the README's own rule, this delta (and the matching MCP citations in rethinking-systems-in-the-agentic-age.md and what-tickets-and-prs-are-actually-for.md) should propose the destination URL, not the redirect source.

Defensible counter-argument: linking the protocol home rather than its docs intro mirrors how anthropic.com or nextjs.org are typically linked (the homepage is the canonical entry, the docs intro is one click in). If that's the intent, the README rule should be softened to allow root-domain canonical surfaces. If the rule is meant to be strict, all three MCP citations should be updated to https://modelcontextprotocol.io/docs/getting-started/intro.

Either resolution is fine — the delta files just shouldn't quietly violate the rule the README states. Suggest either: (a) update the 3 MCP citations to the destination URL, or (b) add one sentence to the README clarifying that root-domain landing pages are exempt from the destination-URL rule when the root is the protocol/product's canonical home.

@julianken
Copy link
Copy Markdown
Owner Author

@Mergifyio queue

@mergify
Copy link
Copy Markdown
Contributor

mergify Bot commented May 17, 2026

Merge Queue Status

  • 🟠 Waiting for queue conditions
  • ⏳ Enter queue
  • ⏳ Run checks
  • ⏳ Merge
Required conditions to enter a queue
  • -closed [📌 queue requirement]
  • -conflict [📌 queue requirement]
  • -draft [📌 queue requirement]
  • any of [📌 queue -> configuration change requirements]:
    • -mergify-configuration-changed
    • check-success = Configuration changed
  • any of [🔀 queue conditions]:
    • all of [📌 queue conditions of queue rule default]:
      • #approved-reviews-by >= 1
      • #approved-reviews-by >= 1 [🛡 GitHub branch protection]
      • #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
      • -conflict
      • -draft
      • base = main
      • check-success = Analyze Bundle
      • check-success = CodeQL Analysis
      • check-success = E2E Shard 1/4
      • check-success = E2E Shard 2/4
      • check-success = E2E Shard 3/4
      • check-success = E2E Shard 4/4
      • check-success = ESLint
      • check-success = Next.js Build
      • check-success = TypeScript
      • check-success = Vitest
      • github-review-decision = APPROVED [🛡 GitHub branch protection]
      • any of [🛡 GitHub branch protection]:
        • check-success = ESLint
        • check-neutral = ESLint
        • check-skipped = ESLint
      • any of [🛡 GitHub branch protection]:
        • check-success = TypeScript
        • check-neutral = TypeScript
        • check-skipped = TypeScript
      • any of [🛡 GitHub branch protection]:
        • check-success = Vitest
        • check-neutral = Vitest
        • check-skipped = Vitest
      • any of [🛡 GitHub branch protection]:
        • check-success = Next.js Build
        • check-neutral = Next.js Build
        • check-skipped = Next.js Build
      • any of [🛡 GitHub branch protection]:
        • check-success = Analyze Bundle
        • check-neutral = Analyze Bundle
        • check-skipped = Analyze Bundle
      • any of [🛡 GitHub branch protection]:
        • check-success = CodeQL Analysis
        • check-neutral = CodeQL Analysis
        • check-skipped = CodeQL Analysis
      • any of [🛡 GitHub branch protection]:
        • check-success = E2E Shard 1/4
        • check-neutral = E2E Shard 1/4
        • check-skipped = E2E Shard 1/4
      • any of [🛡 GitHub branch protection]:
        • check-success = E2E Shard 2/4
        • check-neutral = E2E Shard 2/4
        • check-skipped = E2E Shard 2/4
      • any of [🛡 GitHub branch protection]:
        • check-success = E2E Shard 3/4
        • check-neutral = E2E Shard 3/4
        • check-skipped = E2E Shard 3/4
      • any of [🛡 GitHub branch protection]:
        • check-success = E2E Shard 4/4
        • check-neutral = E2E Shard 4/4
        • check-skipped = E2E Shard 4/4

@mergify mergify Bot added the queued label May 17, 2026
@mergify
Copy link
Copy Markdown
Contributor

mergify Bot commented May 17, 2026

Merge Queue Status

  • Entered queue2026-05-17 18:48 UTC · Rule: default
  • Checks passed · in-place
  • Merged2026-05-17 18:51 UTC · at 2331cd9a2e1e53cb01d0ada0e68af5a2ac47a5c3 · squash

This pull request spent 3 minutes 21 seconds in the queue, including 2 minutes 57 seconds running CI.

Required conditions to merge
  • #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • github-review-decision = APPROVED [🛡 GitHub branch protection]
  • any of [🛡 GitHub branch protection]:
    • check-success = ESLint
    • check-neutral = ESLint
    • check-skipped = ESLint
  • any of [🛡 GitHub branch protection]:
    • check-success = TypeScript
    • check-neutral = TypeScript
    • check-skipped = TypeScript
  • any of [🛡 GitHub branch protection]:
    • check-success = Vitest
    • check-neutral = Vitest
    • check-skipped = Vitest
  • any of [🛡 GitHub branch protection]:
    • check-success = Next.js Build
    • check-neutral = Next.js Build
    • check-skipped = Next.js Build
  • any of [🛡 GitHub branch protection]:
    • check-success = Analyze Bundle
    • check-neutral = Analyze Bundle
    • check-skipped = Analyze Bundle
  • any of [🛡 GitHub branch protection]:
    • check-success = CodeQL Analysis
    • check-neutral = CodeQL Analysis
    • check-skipped = CodeQL Analysis
  • any of [🛡 GitHub branch protection]:
    • check-success = E2E Shard 1/4
    • check-neutral = E2E Shard 1/4
    • check-skipped = E2E Shard 1/4
  • any of [🛡 GitHub branch protection]:
    • check-success = E2E Shard 2/4
    • check-neutral = E2E Shard 2/4
    • check-skipped = E2E Shard 2/4
  • any of [🛡 GitHub branch protection]:
    • check-success = E2E Shard 3/4
    • check-neutral = E2E Shard 3/4
    • check-skipped = E2E Shard 3/4
  • any of [🛡 GitHub branch protection]:
    • check-success = E2E Shard 4/4
    • check-neutral = E2E Shard 4/4
    • check-skipped = E2E Shard 4/4

@mergify mergify Bot merged commit e4656eb into main May 17, 2026
13 checks passed
@mergify mergify Bot deleted the docs/seo-citation-deltas branch May 17, 2026 18:51
@mergify mergify Bot removed the queued label May 17, 2026
mergify Bot pushed a commit that referenced this pull request May 18, 2026
* chore(docs): drop seo-strategy folder; align README to renamed post slug

Removes docs/seo-strategy/ — research artifacts from the SEO + AI-
discovery analysis funnel, no longer load-bearing now that the
gate-1/2/3 work has shipped (#393 #394 #395 #396 #397 #400 #402 #404
#406 #408). History preserved in git.

README: align "Recent essays" entry with the renamed post
slug (where-agentic-patterns-actually-live →
agentic-patterns-in-your-coding-workflow). The rename satisfies Bing
Site Scan's 70-char title cap.

No redirect deployed — article is two days old, no significant
external link equity to preserve.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: defer README slug update; gitignore docs/seo-strategy

Address julianken-bot review of PR #409:

BLOCKER (README:75) — New slug URL serves an SSR 404 fallback because
the Payload post slug hasn't been renamed yet (intentionally deferred
until the in-flight Bing Site Scan completes). Reverting the README
link change here; it will land in a follow-up PR after the actual
Payload slug rename, so the link is never broken in main.

Plus: add /docs/seo-strategy/ to .gitignore so future analysis-funnel
artifacts (phase-*, context-packets, STATUS.md, issues/) stay on disk
without polluting the index.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:seo SEO + AI-discovery strategy work status:in-review PR open, waiting for review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(seo): produce inline-citation delta files for existing posts

2 participants